package cn.mujiankeji.mbrowser.功能.下载.仓库

import cn.mujiankeji.mbrowser.功能.下载.模型.下载任务
import kotlinx.coroutines.flow.Flow

/**
 * 下载仓库接口
 * 定义了对下载任务数据进行操作的统一入口。
 */
interface 下载仓库接口 {

    /**
     * 获取所有下载任务的 Flow 列表。
     * 列表会根据下载任务的创建时间进行排序。
     */
    fun 获取所有下载任务(): Flow<List<下载任务>>

    /**
     * 获取所有活动中（未完成）的下载任务 Flow 列表。
     * 活动任务包括等待中、正在下载、已暂停和失败可重试的状态。
     * 列表会根据优先级（降序）和创建时间（升序）进行排序。
     */
    fun 获取活动下载任务(): Flow<List<下载任务>>

    /**
     * 获取所有已完成的下载任务 Flow 列表。
     * 列表会根据完成时间（降序）进行排序。
     */
    fun 获取已完成下载任务(): Flow<List<下载任务>>

    /**
     * 根据ID获取单个下载任务的 Flow。
     * 如果任务不存在，Flow 将发射 null。
     * @param 任务Id 要获取的任务的唯一标识符。
     */
    fun 获取下载任务(任务Id: String): Flow<下载任务?>

    /**
     * 添加一个新的下载任务到仓库。
     * @param 任务 要添加的下载任务对象。
     * @return 返回被添加任务的ID。
     */
    suspend fun 添加下载任务(任务: 下载任务): String

    /**
     * 更新一个已存在的下载任务。
     * @param 任务 包含更新信息的下载任务对象。
     */
    suspend fun 更新下载任务(任务: 下载任务)

    /**
     * 根据ID删除一个下载任务。
     * @param 任务Id 要删除的任务的唯一标识符。
     */
    suspend fun 删除下载任务(任务Id: String)

    /**
     * 清空所有已完成的下载任务历史。
     * （或者清空所有任务，根据具体需求调整，文档写的是清空下载历史，通常指已完成的）
     * 这里我们定义为清空所有任务，与Dao中的清空所有下载任务对应。
     * 如果需要更细致的"清空已完成"，可以在实现类中添加逻辑或在Dao中新增方法。
     */
    suspend fun 清空下载历史()

    /**
     * 根据ID获取单个下载任务的快照。
     * 如果任务不存在，则返回 null。
     * @param 任务Id 要获取的任务的唯一标识符。
     */
    suspend fun 获取下载任务快照(任务Id: String): 下载任务?

    /**
     * 获取特定状态的下载任务快照列表。
     * @param 状态码 目标状态的ordinal值。
     */
    suspend fun 获取特定状态任务快照列表(状态码: Int): List<下载任务>


} 